package com.lb.ai.swagger.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.*;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.Arrays;
import java.util.Collections;

/**
 * OpenAPI (SpringDoc) 配置类
 * 用于配置API文档信息和安全认证
 * 
 * <p>主要功能：
 * <ul>
 *   <li>配置API文档的基本信息：项目标题、描述、版本等</li>
 *   <li>配置文档联系人信息：姓名、邮箱、网站等</li>
 *   <li>配置API许可证信息：类型、使用地址等</li>
 *   <li>配置安全认证方案：JWT Token认证、Basic认证等</li>
 *   <li>配置服务器信息：开发环境、生产环境等</li>
 *   <li>配置全局安全要求：接口访问权限等</li>
 * </ul>
 * 
 * <p>使用说明：
 * <ul>
 *   <li>访问Knife4j文档：http://localhost:8080/doc.html</li>
 *   <li>访问Swagger文档：http://localhost:8080/swagger-ui.html</li>
 *   <li>访问OpenAPI规范：http://localhost:8080/v3/api-docs</li>
 * </ul>
 * 
 * @author LiuJianning
 * @version 1.0.0
 * @since 2024-01-01
 */
@Configuration
public class OpenApiConfig {

    /**
     * OpenAPI配置方法
     * 配置API文档的基本信息和安全认证
     *
     * <p>配置内容包括：
     * <ul>
     *   <li>文档基本信息：通过{@link #apiInfo()}方法配置</li>
     *   <li>服务器信息：配置本地和生产环境地址</li>
     *   <li>安全组件：通过{@link #securityComponents()}方法配置</li>
     *   <li>安全要求：通过{@link #globalSecurityRequirement()}方法配置</li>
     * </ul>
     *
     * @return OpenAPI配置实例
     */
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                // 文档基本信息
                .info(apiInfo())
                // 服务器配置
                .servers(Arrays.asList(
                    new Server().url("/").description("本地环境"),
                    new Server().url("https://api.example.com").description("生产环境")
                ))
                // 安全配置
                .components(securityComponents())
                // 全局安全要求
                .addSecurityItem(globalSecurityRequirement());
    }

    /**
     * API文档基本信息配置
     * 
     * <p>配置内容包括：
     * <ul>
     *   <li>文档标题：项目名称</li>
     *   <li>文档描述：项目描述信息</li>
     *   <li>文档版本：项目当前版本</li>
     *   <li>联系人信息：开发者联系方式</li>
     *   <li>许可证信息：项目使用的开源协议</li>
     * </ul>
     *
     * @return Info 文档信息配置对象
     */
    private Info apiInfo() {
        return new Info()
                .title("Common Tools API文档")
                .description("Common Tools项目接口文档，基于OpenAPI 3规范")
                .version("1.0.0")
                .contact(new Contact()
                        .name("LiuJianning")
                        .email("your-email@example.com")
                        .url("https://github.com/yourusername"))
                .license(new License()
                        .name("Apache 2.0")
                        .url("https://www.apache.org/licenses/LICENSE-2.0.html"));
    }

    /**
     * 安全组件配置方法
     * 配置API接口的认证方式
     * 
     * <p>支持的认证方式：
     * <ul>
     *   <li>JWT Token认证：Bearer token方式</li>
     *   <li>Basic认证：用户名密码方式</li>
     * </ul>
     * 
     * <p>认证说明：
     * <ul>
     *   <li>JWT认证：需要在请求头中添加Authorization: Bearer {token}</li>
     *   <li>Basic认证：需要在请求头中添加Basic Base64(username:password)</li>
     * </ul>
     *
     * @return Components 安全组件配置对象
     */
    private Components securityComponents() {
        return new Components()
                // JWT Token认证
                .addSecuritySchemes("Authorization", new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")
                        .in(SecurityScheme.In.HEADER)
                        .name("Authorization")
                        .description("JWT Token认证，格式: Bearer {token}"))
                // Basic认证
                .addSecuritySchemes("basic", new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("basic")
                        .in(SecurityScheme.In.HEADER)
                        .description("Basic认证"));
    }

    /**
     * 全局安全要求配置方法
     * 配置API接口的全局安全要求
     * 
     * <p>配置说明：
     * <ul>
     *   <li>JWT Token：配置read和write权限范围</li>
     *   <li>Basic认证：不需要特定的权限范围</li>
     * </ul>
     * 
     * <p>注意：此配置将应用于所有未单独配置安全要求的接口
     *
     * @return SecurityRequirement 安全要求配置对象
     */
    private SecurityRequirement globalSecurityRequirement() {
        return new SecurityRequirement()
                .addList("Authorization", Arrays.asList("read", "write"))
                .addList("basic", Collections.emptyList());
    }
} 